Pascal Super Library

home *** CD-ROM | disk | FTP | other *** search

/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / TURB_VIS / TVLIST / TVLIST.DOC < prev next >

Wrap

Text File | 1991-03-17 | 35KB | 1,057 lines

C H A P T E R ------------------------------------------------------------ TVList Object Reference This chapter contains a listing of all the classes, procedures, and types included in the TVList Unit. TList Abstract Class TVList ------------------------------------------------------------ TObject -> TCollection -> TList TList is an abstract Class that extends the functionality of the TCollection Class. It can be used to implment Lists or Collections of TObject objects or descendant objects. It provides a structure for implementing TObjects with any data structure, and yet use these with TListBoxer, TListDialog, and TListDialogInputField objects. It is also extended to provide simple editing adding, and deleting of list items. See also: TCollection Methods ------------------------------------------- CreateItem function CreateItem(Corner:Tpoint):pointer; virtual; Override:Often Used to create List items to be inserted into TList. Can be done with user defined dialog box or any other means. Returns a nil pointer if no item was created. Need no be redefined for each descendant class. Deafault will simply return a nil pointer. Only needs to be defined if the Add option will be used with TListDialog. Corner will be passed by TListDialog in Absolute coordinates. This is the requested location for any TDialog used. User must determine if a dialog can be located at Corner. The procedure MakeTrect() can be used for this purpose. See Also: MakeTrect(), TPointAssign() TVList 2 EditItem procedure EditItem(Corner:TPoint; Item:pointer); virtual; Override:Often Used to edit List items. Item is a pointer to a List item, a PObject or descendant type. Editing can be with a dialog or someother means. Corner will be passed by TListDialog in Absolute coordinates. This is the requested location for any TDialog used. User must determine if a dialog can be located at Corner. The procedure MakeTrect() can be used for this purpose. See also: MakeRect(), TPointAssign() GetItemText function GetItemText(Item:pointer; MaxLen:integer):string; virtual; Override:Always This returns a string that will be used to display a List item's data in a ListBoxer object. Item is a pointer to the List item, ussually a PObject or descendant object. The string returned should be MaxLen or less in length. Must be redefined for each new Class. Uses the abstract method to halt the program if not redefined. See also: Abstract, TListBoxer.GetText, TListBox.GetText AtAddNewItem function AtAddNewItem(Corner:TPoint; Index:integer):pointer; Override:Never Adds a List item to the TList at the Index location. Calls AtInsert(Index,CreateItem(Corner)). Use EndOf Collection to add to the end of the List and 0 to add to the beginning of the list. Called by TlistDialog. See also: TListDialog MaxTextLength function MaxTextLength:word; Override:Never Returns the length of the longest GetItemText() in the List. Uses ForEach(). Used to determine how wide a ListBox will have to be, so TListDialog can dynamically allocate a dialog size. TVList 3 TSortedList Abstract Class TVList ------------------------------------------------------------ TObject -> TSortedCollection -> TSortedList TSortedList is an abstract Class that extends the functionality of the TSortedCollection Class. It can be used to implment Lists or Collections of TObject objects or descendant objects. It provides a structure for implementing TObjects with any data structure, and yet use these with TSortedListBoxer, TSortedListDialog, and TListDialogInputField objects. It is also extended to provide simple editing adding, and deleting of list items. It will insert items in the list in a sorted fashion. In addition to the methods below, the KeyOf() and Compare() methods must also be defined. See also: TSortedCollection Methods ------------------------------------------- CreateItem function CreateItem(Corner:Tpoint):pointer; virtual; Override:Often Used to create List items to be inserted into TSortedList. Can be done with user defined dialog box or any other means. Returns a nil pointer if no item was created. Need not be redefined for each descendant class. Deafault will simply return a nil pointer. Only needs to be defined if the Add option will be used with TListDialog. Corner will be passed by TSortedListDialog in Absolute coordinates. This is the requested location for any TDialog used. User must determine if a dialog can be located at Corner. The procedure MakeTrect() can be used for this purpose. See Also: MakeTrect(), TPointAssign() EditItem procedure EditItem(Corner:TPoint; Item:pointer); virtual; Override:Often Used to edit List items. Item is a pointer to a List item, a PObject or descendant type. Editing can be with a dialog or someother means. Corner will be passed by TSortedListDialog in Absolute TVList 4 coordinates. This is the requested location for any TDialog used. User must determine if a dialog can be located at Corner. The procedure MakeTrect() can be used for this purpose. See also: MakeRect(), TPointAssign() GetItemText function GetItemText(Item:pointer; MaxLen:integer):string; virtual; Override:Always This returns a string that will be used to display a List item's data in a ListBoxer object. Item is a pointer to the List item, ussually a PObject or descendant object. The string returned should be MaxLen or less in length. Must be redefined for each new Class. Uses the abstract method to halt the program if not redefined. See also: Abstract, TListBoxer.GetText, TListBox.GetText AtAddNewItem function AtAddNewItem(Corner:TPoint):pointer; Override:Never Adds a List item to the TList at the Index location. Will place it in the List in sorted position. Calls Insert(CreateItem(Corner)). Called by TSortedListDialog. See also: TSortedListDialog, TSortedCollection.KeyOf, TSortedCollection.Compare. MaxTextLength function MaxTextLength:word; Override:Never Returns the length of the longest GetItemText() in the List. Uses ForEach(). Used to determine how wide a ListBox will have to be, so TSortedListDialog can dynamically allocate a dialog size. TVList 5 TListBoxer Class TVList ------------------------------------------------------------ TObject -> TView -> TListViewer -> TListBox -> TListBoxer TListBoxer is a simple descendant of TListBox. It primarily wraps TlistBox.GetText around a call to TList.GetItemText. It also passes control to its owner when the enter key or a double mouse click is used to select an item. Methods ------------------------------------------- GetText function GetText(Item:Integer; MaxLen:integer):string; virtual; Override:Seldom Calls PList(List)^.GetItemText(List^.At(Item),Max Len); See also: TListBox.GetText HandleEvent procedure HandleEvent(var Event:TEvent); virtual; Override:Seldom Traps Enter key and cmListItemSelected before calling TListBox.HandleEvent. See also: TListBox.HandleEvent TVList 6 TSortedListBoxer Class TVList ------------------------------------------------------------ TObject -> TView -> TListViewer -> TListBox -> TListBoxer -> TSortedListBoxer TSortedListBoxer is a simple descendant of TListBox. It primarily wraps TSortedlistBox.GetText around a call to TSortedList.GetItemText. It also passes control to its owner when the enter key or a double mouse click is used to select an item. Methods ------------------------------------------- GetText function GetText(Item:Integer; MaxLen:integer):string; virtual; Override:Seldom Calls PList(List)^.GetItemText(List^.At(Item),Max Len); See also: TListBox.GetText TVList 7 TListDialog Class TVList ------------------------------------------------------------ TObject -> TView -> TGroup -> TWindow -> TDialog -> TListDialog TListDialog is a highly tuned Dialog to be used with TList objects to display a TList in a ListBox. It can serve a variety of functions. It can be used to simply display the items in a Tlist object with a ListBox, it can be used to select items from a Tlist Object with a ListBox, it can be used to edit, add, and or delete items from a TList object using a ListBox. The intent of this Class is to provide a well supported and flexible user interface for TList objects that requires little redefinition, and can be setup and executed with a minimal amount of code and support. TListDialog inserts at a minimum a TListBoxer, an cmOK TButton, and a cmCancel TButton. Based on the values passed in Behavior with Init, an Add TButton, Edit TButton, and/or Delete TButton are also provided. The size and location of the TDialog object can be dynamically calculated by Init. TlistDialog has the following properties: o Enter key is trapped and used to select a highlighted item in the listbox when the listbox is selected or select a button. o Up and Down Cursor keys can be used to scroll the List Box or move from Button to Button in the dialog box. o Esc key or Cancel button generates a cmCancel evCommand event. Item Selected from List Box is not returned, BUT any items added, edited, or deleted will not be restored to their state when the dialog was executed. o Double Click of the mouse in the ListBox selects the item. o All other default properties of TDialog objects remain. TVList 8 The behavior of the Dialog is controlled by the AB field which can set with the Behavior parameter with in init constructor. The bits of the AB behavior field are defined as follows: msb lsb [][][][][][][][] Constants | | | | | | | | | | | `---- sfAdd = $01 | | | | `------ sfDelete = $02 | | | `-------- sfEdit = $04 | | `---------- sfSearch = $08 | `------------ sfPromptDelete = $10 `-------------- SfPromptExit = $20 Two general purpose constant masks are: sfFullEdit = sfAdd + sfDelete + sfEdit; sfDoall = $FF; With sfAdd bit set TListDialogs will insert a ADD button in the dialog. Slection of this button will call TList.CreateItem. If this has not be redefined, then nothing happens. With sfDelete bit set TListDialogs will insert a DELETE button. Selection of the button will delete the currently selected item in the list box. With sfEdit bit set TListDialogs will insert an EDIT button in the dialog. Selecting this button will call TList.EditItem. If this is not defined then nothing happens. If using a TSortedList with TSortedList (see Below), with the sfSearch bit set the Dialog will allow keystrokes to be used to do an incremental search of the Tlistbox when the listbox is selected. As each key is pressed the search string is displayed on a search line and the TListbox moves the focus to the item that most closely matches the search string. Using the backspace key will delete keys from the searchline. With the sfPromptDelete bit set, the dialog will promote for approval before a Delete is preformed. TVList 9 With the sfPromptExit bit set, the dialog will move to the OK button on a selection from the List box. This provides a way to verify a selection before exiting the dialog. With this bit unset, selecting an item in the list box (with the mouse or pressing enter) exits the dialog. Fields ------------------------------------------- AB AB : byte; Read only This is used to determine what the behavior of the Dialog will be. See definition of mask bits above. See also: TListDialog.Init TLR TLR:TListRec; Read only This is used to store the index and pointer of the focused item in ListBox when the dialog is closed after selecting an item from the ListBox. Max Max:byte; Read only The is the Maximum width of the GetItemText with in the List being used. List List:pointer; Read only This is a pointer to a Plist object that has been initialized. LB LB:PlistBox; Read only This is a pointer to the ListBoxer being used to display the List. X,Y X,Y:word; Read only This is the location of a status line used by the Dialog. This is used to locate where the ListBox header will be located. This is also used by TSortedListDialog to display the active search string. SearchString SearchString:PString; Read only This is the current string being used to incrementally search through List. TVList 10 Methods ------------------------------------------- Init constructor Init(var Bounds:Trect; ATitle:TTitleStr; Behavior:byte; TheList:PList; BoxHeader:TTitleStr); Override:Never Bounds is the location and size of the desired dialog box. This may be resized and reloacted if sufficient room is not provided. If bounds is assigned with Bounds.assign(X,Y,0,0) then a dialog box is opened with upper left corner at XY and with a listbox of 4 lines and sized to accomodate all behavior buttons. ATitle will be used for the Dialogs title. Behavior is a set of flags that can be passed to activate certain functions in the Dialog box. TheList is the list! This is a PLIST class instances that contians a list of data records. BoxHeader is an optional string that will be used a Tlabel for the ListBox. This can be useful if the GetItemText() string actually contains data from multiple fields. BoxHeader can be used to label these fields. See also: AB DataSize function DataSize: word; virtual; OverRide:Never Default is to return sizeof(TListRec). GetData procedure GetData(var rec); virtual; OverRide:Never Default is to return a pointer to a TListRec data type. Returns a TListRec datatype where TListRec.item is a pointer to the selected object in the List, if the Dialog concluded with a cmOk command. Returns a nil pointer in TListRec.Item otherwise. TListRec.Index provides the index to the item that was selected. SetData procedure SetData(var rec); virtual; OverRide:Never Default is to move a TListRec into Rec. TVList 11 HandleEvent procedure HandleEvent(var Event:TEvent); virtual; Override:Seldom Handles interaction between ListBox and Dialog TVList 12 TSortedListDialog Class TVList ------------------------------------------------------------ TObject -> TView -> TGroup -> TWindow -> TDialog -> TListDialog -> TSortedListDialog Provides same functions of TListDialog, but is used with TSortedList object. TSortedListDialog can provide incremental scrolling of the list box based on a search string. While the ListBox is active, a string can be entered from the key board. As each key is detected, the ListBox is searched for the closest matching string. When this search feature is active, the spacebar can not be used to select from th ListBox. Methods ------------------------------------------- Init constructor init(var Bounds:Trect; ATitle:TTitleStr;Behavior:byte; TheList:PSortedList; BoxHeader:TTitleStr); Same as PListDialog.init except TheList is a PSortedList class. See also: TListDialog.init HandleEvent procedure HandleEvent(var Event:TEvent); virtual; Override:Seldom Handles interaction between ListBox and Dialog similar to TlistDialog, but also provides for an incremental search of ListBox based on a searchstring entered from the keyboard. See also: TListDialog.HandleEvent TVList 13 TListDialogInputField Class ------------------------------------------------------------ TObject -> TView -> TInputLine -> TListDialogInputField This class is a descendant of TInputline, however it does no allow entry of data. It is used to execute a TListDialog or TSortedListDialog from within another dialog. It is inserted into a dialog just like anyother TInputLine object. When the dialog is executed this field displays the string value of item at the position set by setdata. When this field is selected, pressing the Ins key or the right or left arrow keys will execute a Tlist dialog. After this TList dialog is closed, this field will display the item selected in the TList Dialog. IT provides a convient way to insert ListBoxes in dialogs with out taking up a lot of screen space. Fields ------------------------------------------- TD TD:pointer; Read Only Pointer to TListDialog TL TL:pointer; Read Only Pointer to TList Max Max:byte; Read Only Maximum string value returned by TL^.GetItemText Index Index:word; Read Only Index of Listbox, Set by SetData Sorted Sorted:boolean; Read Only Indicates that TL is a TSortedList object pointer. TVList 14 Methods ------------------------------------------- Init constructor init (Field:TPoint; ListLocation:Tpoint; ListHeight:word; Title:String; Behavior:byte; AList:Pointer; BoxHeader:string; SortedList:boolean); Override:Seldom Field is the left X,Y of the location in the dialog. ListLocation is the X,Y location relative to the Field location where the TlistDialog should be located. DataSize function DataSize:word; virtual; Override:Seldom Default returns a value of 2 GetData procedure GetData(Var Rec); virtual; Override:Seldom Default moves a word size value into Rec from the Index field. SetData procedure SetData(Var Rec); virtual; Override:Seldom Deafault moves a word size value from Rec into the Index field. HandleEvent procedure HandleEvent(var Event:TEvent); virtual; Override:Seldom Handles user input. kbEnter is translated to a kbTab. kbIns, kbRight, and kbLeft and mouse double click executes the TListDialog. TVList 15 RegisterTVList procedure ------------------------------------------------------------ Declaration procedure RegisterTVList; Function Registers TList and TSortedList objects. ObjType codes are TList, 2000 and TSortedList 2001 The IDs used to register TV objects are TList 200 TSortedList 201 MakeRect procedure ------------------------------------------------------------ Declaration procedure MakeRect(Corner:Tpoint; Xsize,YSize:integer; var Bounds:Trect); Function This procedure takes Corner, which should be in global coordinates, and trys to create a Rectangle with an upper left Corner and is XSize wide and YSize high. If this is not possible, it will try and adjust Corner to a location where such a rectangle can be displayed. Failing that it will create the Largest Rectangle that can be displayed. TPointAssign procedure ------------------------------------------------------------ Declaration Procedure TPointAssign(var P:TPoint; X,Y:integer); Function This procedure simply assigns X,Y to the Tpoint object, easier than P.X := X; P.Y:=Y; TListRec type ------------------------------------------------------------ Declaration TListRec = record Item:pointer; Index:integer; end; TVList 16 Function Data type used with TListDialog and TSortedListDialog methods GetData and Setdata. Item points to the item which was selected from the dialogs list box on exit. Index is its index into the list.